home *** CD-ROM | disk | FTP | other *** search
Text File | 1992-08-06 | 49.3 KB | 1,395 lines
Info file: cmu-user.info, -*-Text-*- produced by latexinfo-format-buffer from file: cmu-user.tex File: cmu-user.info Node: With Object Sets, Prev: Without Object Sets, Up: Using SERVE-EVENT with the CLX Interface to X With Object Sets ---------------- This section discusses the use of object sets and `system:serve-event' to handle CLX events. This is necessary when a single X application has distinct windows that want to handle the same events in different ways. Basically, you need some way of asking for a given window which way you want to handle some event because this event is handled differently depending on the window. Object sets provide this feature. For each CLX event-key symbol-name XXX (for example, KEY-PRESS), there is a function `serve-'XXX of two arguments, an object set and a function. The `serve-'XXX function establishes the function as the handler for the :XXX event in the object set. Recall from section *Note Object Sets::, `system:add-xwindow-object' associates some Lisp object with a CLX window in an object set. When `system:serve-event' notices activity on a window, it calls the function given to `ext:enable-clx-event-handling'. If this function is `ext:object-set-event-handler', it calls the function given to `serve-'XXX, passing the object given to `system:add-xwindow-object' and the event's slots as well as a couple other arguments described below. To use object sets in this way: * Create an object set. * Define some operations on it using the `serve-'XXX functions. * Add an object for every window on which you receive requests. This can be the CLX window itself or some structure more meaningful to your application. * Call `system:serve-event' to service an X event. -- Function: object-set-event-handler DISPLAY This function is a suitable argument to `ext:enable-clx-event-handling'. The actual event handlers defined for particular events within a given object set must take an argument for every slot in the appropriate event. In addition to the event slots, `ext:object-set-event-handler' passes the following arguments: * The object, as established by `system:add-xwindow-object', on which the event occurred. * event-key, see `xlib:event-case'. * send-event-p, see `xlib:event-case'. Describing any `ext:serve-'EVENT-KEY-NAME function, where EVENT-KEY-NAME is an event-key symbol-name (for example, `ext:serve-key-press'), indicates exactly what all the arguments are in their correct order. When creating an object set for use with `ext:object-set-event-handler', specify `ext:default-clx-event-handler' as the default handler for events in that object set. If no default handler is specified, and the system invokes the default default handler, it will cause an error since this function takes arguments suitable for handling port messages. File: cmu-user.info Node: A SERVE-EVENT Example, Prev: Using SERVE-EVENT with the CLX Interface to X, Up: Event Dispatching with SERVE-EVENT A SERVE-EVENT Example ===================== This section contains two examples using `system:serve-event'. The first one does not use object sets, and the second, slightly more complicated one does. * Menu: * Without Object Sets Example:: * With Object Sets Example:: File: cmu-user.info Node: Without Object Sets Example, Prev: A SERVE-EVENT Example, Up: A SERVE-EVENT Example, Next: With Object Sets Example Without Object Sets Example --------------------------- This example defines an input handler for a CLX display connection. It only recognizes :key-press events. The body of the example loops over `system:serve-event' to get input. (in-package "SERVER-EXAMPLE") (defun my-input-handler (display) (xlib:event-case (display :timeout 0) (:key-press (event-window code state) (format t "KEY-PRESSED (Window = ~D) = ~S.~%" (xlib:window-id event-window) ;; See Hemlock Command Implementor's Manual for convenient ;; input mapping function. (ext:translate-character display code state)) ;; Make XLIB:EVENT-CASE discard the event. t))) (defun server-example () "An example of using the SYSTEM:SERVE-EVENT function and object sets to handle CLX events." (let* ((display (ext:open-clx-display)) (screen (display-default-screen display)) (black (screen-black-pixel screen)) (white (screen-white-pixel screen)) (window (create-window :parent (screen-root screen) :x 0 :y 0 :width 200 :height 200 :background white :border black :border-width 2 :event-mask (xlib:make-event-mask :key-press)))) ;; Wrap code in UNWIND-PROTECT, so we clean up after ourselves. (unwind-protect (progn ;; Enable event handling on the display. (ext:enable-clx-event-handling display #'my-input-handler) ;; Map the windows to the screen. (map-window window) ;; Make sure we send all our requests. (display-force-output display) ;; Call serve-event for 100,000 events or immediate timeouts. (dotimes (i 100000) (system:serve-event))) ;; Disable event handling on this display. (ext:disable-clx-event-handling display) ;; Get rid of the window. (destroy-window window) ;; Pick off any events the X server has already queued for our ;; windows, so we don't choke since SYSTEM:SERVE-EVENT is no longer ;; prepared to handle events for us. (loop (unless (deleting-window-drop-event *display* window) (return))) ;; Close the display. (xlib:close-display display)))) (defun deleting-window-drop-event (display win) "Check for any events on win. If there is one, remove it from the event queue and return t; otherwise, return nil." (xlib:display-finish-output display) (let ((result nil)) (xlib:process-event display :timeout 0 :handler #'(lambda (&key event-window &allow-other-keys) (if (eq event-window win) (setf result t) nil))) result)) File: cmu-user.info Node: With Object Sets Example, Prev: Without Object Sets Example, Up: A SERVE-EVENT Example With Object Sets Example ------------------------ This example involves more work, but you get a little more for your effort. It defines two objects, `input-box' and `slider', and establishes a :key-press handler for each object, `key-pressed' and `slider-pressed'. We have two object sets because we handle events on the windows manifesting these objects differently, but the events come over the same display connection. (in-package "SERVER-EXAMPLE") (defstruct (input-box (:print-function print-input-box) (:constructor make-input-box (display window))) "Our program knows about input-boxes, and it doesn't care how they are implemented." display ; The CLX display on which my input-box is displayed. window) ; The CLX window in which the user types. ;;; (defun print-input-box (object stream n) (declare (ignore n)) (format stream "#<Input-Box ~S>" (input-box-display object))) (defvar *input-box-windows* (system:make-object-set "Input Box Windows" #'ext:default-clx-event-handler)) (defun key-pressed (input-box event-key event-window root child same-screen-p x y root-x root-y modifiers time key-code send-event-p) "This is our :key-press event handler." (declare (ignore event-key root child same-screen-p x y root-x root-y time send-event-p)) (format t "KEY-PRESSED (Window = ~D) = ~S.~%" (xlib:window-id event-window) ;; See Hemlock Command Implementor's Manual for convenient ;; input mapping function. (ext:translate-character (input-box-display input-box) key-code modifiers))) ;;; (ext:serve-key-press *input-box-windows* #'key-pressed) (defstruct (slider (:print-function print-slider) (:include input-box) (:constructor %make-slider (display window window-width max))) "Our program knows about sliders too, and these provide input values zero to max." bits-per-value ; bits per discrete value up to max. max) ; End value for slider. ;;; (defun print-slider (object stream n) (declare (ignore n)) (format stream "#<Slider ~S 0..~D>" (input-box-display object) (1- (slider-max object)))) ;;; (defun make-slider (display window max) (%make-slider display window (truncate (xlib:drawable-width window) max) max)) (defvar *slider-windows* (system:make-object-set "Slider Windows" #'ext:default-clx-event-handler)) (defun slider-pressed (slider event-key event-window root child same-screen-p x y root-x root-y modifiers time key-code send-event-p) "This is our :key-press event handler for sliders. Probably this is a mouse thing, but for simplicity here we take a character typed." (declare (ignore event-key root child same-screen-p x y root-x root-y time send-event-p)) (format t "KEY-PRESSED (Window = ~D) = ~S --> ~D.~%" (xlib:window-id event-window) ;; See Hemlock Command Implementor's Manual for convenient ;; input mapping function. (ext:translate-character (input-box-display slider) key-code modifiers) (truncate x (slider-bits-per-value slider)))) ;;; (ext:serve-key-press *slider-windows* #'slider-pressed) (defun server-example () "An example of using the SYSTEM:SERVE-EVENT function and object sets to handle CLX events." (let* ((display (ext:open-clx-display)) (screen (display-default-screen display)) (black (screen-black-pixel screen)) (white (screen-white-pixel screen)) (iwindow (create-window :parent (screen-root screen) :x 0 :y 0 :width 200 :height 200 :background white :border black :border-width 2 :event-mask (xlib:make-event-mask :key-press))) (swindow (create-window :parent (screen-root screen) :x 0 :y 300 :width 200 :height 50 :background white :border black :border-width 2 :event-mask (xlib:make-event-mask :key-press))) (input-box (make-input-box display iwindow)) (slider (make-slider display swindow 15))) ;; Wrap code in UNWIND-PROTECT, so we clean up after ourselves. (unwind-protect (progn ;; Enable event handling on the display. (ext:enable-clx-event-handling display #'ext:object-set-event-handler) ;; Add the windows to the appropriate object sets. (system:add-xwindow-object iwindow input-box *input-box-windows*) (system:add-xwindow-object swindow slider *slider-windows*) ;; Map the windows to the screen. (map-window iwindow) (map-window swindow) ;; Make sure we send all our requests. (display-force-output display) ;; Call server for 100,000 events or immediate timeouts. (dotimes (i 100000) (system:serve-event))) ;; Disable event handling on this display. (ext:disable-clx-event-handling display) (delete-window iwindow display) (delete-window swindow display) ;; Close the display. (xlib:close-display display)))) (defun delete-window (window display) ;; Remove the windows from the object sets before destroying them. (system:remove-xwindow-object window) ;; Destroy the window. (destroy-window window) ;; Pick off any events the X server has already queued for our ;; windows, so we don't choke since SYSTEM:SERVE-EVENT is no longer ;; prepared to handle events for us. (loop (unless (deleting-window-drop-event display window) (return)))) (defun deleting-window-drop-event (display win) "Check for any events on win. If there is one, remove it from the event queue and return t; otherwise, return nil." (xlib:display-finish-output display) (let ((result nil)) (xlib:process-event display :timeout 0 :handler #'(lambda (&key event-window &allow-other-keys) (if (eq event-window win) (setf result t) nil))) result)) File: cmu-user.info Node: Alien Objects, Prev: Event Dispatching with SERVE-EVENT, Up: Top, Next: Interprocess Communication under LISP Alien Objects ************* By Robert MacLachlan and William Lott * Menu: * Introduction to Aliens:: * Alien Types:: * Alien Operations:: * Alien Variables:: * Alien Data Structure Example:: * Loading Unix Object Files:: * Alien Function Calls:: * Step-by-Step Alien Example:: File: cmu-user.info Node: Introduction to Aliens, Prev: Alien Objects, Up: Alien Objects, Next: Alien Types Introduction to Aliens ====================== Because of Lisp's emphasis on dynamic memory allocation and garbage collection, Lisp implementations use unconventional memory representations for objects. This representation mismatch creates problems when a Lisp program must share objects with programs written in another language. There are three different approaches to establishing communication: * The burden can be placed on the foreign program (and programmer) by requiring the use of Lisp object representations. The main difficulty with this approach is that either the foreign program must be written with Lisp interaction in mind, or a substantial amount of foreign "glue" code must be written to perform the translation. * The Lisp system can automatically convert objects back and forth between the Lisp and foreign representations. This is convenient, but translation becomes prohibitively slow when large or complex data structures must be shared. * The Lisp program can directly manipulate foreign objects through the use of extensions to the Lisp language. Most Lisp systems make use of this approach, but the language for describing types and expressing accesses is often not powerful enough for complex objects to be easily manipulated. CMU Common Lisp relies primarily on the automatic conversion and direct manipulation approaches: Aliens of simple scalar types are automatically converted, while complex types are directly manipulated in their foreign representation. Any foreign objects that can't automatically be converted into Lisp values are represented by objects of type `alien-value'. Since Lisp is a dynamically typed language, even foreign objects must have a run-time type; this type information is provided by encapsulating the raw pointer to the foreign data within an `alien-value' object. The Alien type language and operations are most similar to those of the C language, but Aliens can also be used when communicating with most other languages that can be linked with C. File: cmu-user.info Node: Alien Types, Prev: Introduction to Aliens, Up: Alien Objects, Next: Alien Operations Alien Types =========== Alien types have a description language based on nested list structure. For example: struct foo { int a; struct foo *b[100]; }; has the corresponding Alien type: (struct foo (a int) (b (array (* (struct foo)) 100))) * Menu: * Defining Alien Types:: * Alien Types and Lisp Types:: * Alien Type Specifiers:: * The C-Call Package:: File: cmu-user.info Node: Defining Alien Types, Prev: Alien Types, Up: Alien Types, Next: Alien Types and Lisp Types Defining Alien Types -------------------- Types may be either named or anonymous. With structure and union types, the name is part of the type specifier, allowing recursively defined types such as: (struct foo (a (* (struct foo)))) An anonymous structure or union type is specified by using the name nil. The with-alien ? macro defines a local scope which "captures" any named type definitions. Other types are not inherently named, but can be given named abbreviations using `def-alien-type'. -- Macro: def-alien-type name type This macro globally defines NAME as a shorthand for the Alien type TYPE. When introducing global structure and union type definitions, NAME may be nil, in which case the name to define is taken from the type's name. File: cmu-user.info Node: Alien Types and Lisp Types, Prev: Defining Alien Types, Up: Alien Types, Next: Alien Type Specifiers Alien Types and Lisp Types -------------------------- The Alien types form a subsystem of the CMU Common Lisp type system. An `alien' type specifier provides a way to use any Alien type as a Lisp type specifier. For example (typep foo '(alien (* int))) can be used to determine whether `foo' is a pointer to an `int'. `alien' type specifiers can be used in the same ways as ordinary type specifiers (like `string'.) Alien type declarations are subject to the same precise type checking as any other declaration (section *Note Precise Type Checking::.) Note that the Alien type system overlaps with normal Lisp type specifiers in some cases. For example, the type specifier `(alien single-float)' is identical to `single-float', since Alien floats are automatically converted to Lisp floats. When `type-of' is called on an Alien value that is not automatically converted to a Lisp value, then it will return an `alien' type specifier. File: cmu-user.info Node: Alien Type Specifiers, Prev: Alien Types and Lisp Types, Up: Alien Types, Next: The C-Call Package Alien Type Specifiers --------------------- Some Alien type names are CMU Common Lispsymbols, but the names are still exported from the `alien' package, so it is legal to say `alien:single-float'. These are the basic Alien type specifiers: -- Alien type: TYPE A pointer to an object of the specified TYPE. If TYPE is true, then it means a pointer to anything, similar to "`void *'" in ANSI C. Currently, the only way to detect a null pointer is: (zerop (sap-int (alien-sap PTR))) *Note System Area Pointers:: -- Alien type: array TYPE {DIMENSION}* An array of the specified DIMENSIONS, holding elements of type TYPE. Note that `(* int)' and `(array int)' are considered to be different types when type checking is done; pointer and array types must be explicitly coerced using `cast'. Arrays are accessed using `deref', passing the indices as additional arguments. Elements are stored in column-major order (as in C), so the first dimension determines only the size of the memory block, and not the layout of the higher dimensions. An array whose first dimension is variable may be specified by using nil as the first dimension. Fixed-size arrays can be allocated as array elements, structure slots or `with-alien' variables. Dynamic arrays can only be allocated using make-alien ?. -- Alien type: struct NAME {(FIELD TYPE [BITS])}* A structure type with the specified NAME and FIELDS. Fields are allocated at the same positions used by the implementation's C compiler. BITS is intended for C-like bit field support, but is currently unused. If NAME is false, then the type is anonymous. If a named Alien `struct' specifier is passed to def-alien-type *Note Defining Alien Types:: or with-alien ?, then this defines, respectively, a new global or local Alien structure type. If no FIELDS are specified, then the fields are taken from the current (local or global) Alien structure type definition of NAME. -- Alien type: union NAME {(FIELD TYPE [BITS])}* Similar to `struct', but defines a union type. All fields are allocated at the same offset, and the size of the union is the size of the largest field. The programmer must determine which field is active from context. -- Alien type: enum NAME {SPEC}* An enumeration type that maps between integer values and keywords. If NAME is false, then the type is anonymous. Each SPEC is either a keyword, or a list `(KEYWORD VALUE)'. If INTEGER is not supplied, then it defaults to one greater than the value for the preceding spec (or to zero if it is the first spec.) -- Alien type: signed [BITS] A signed integer with the specified number of bits precision. The upper limit on integer precision is determined by the machine's word size. If no size is specified, the maximum size will be used. -- Alien type: integer [BITS] Identical to `signed' --- the distinction between `signed' and `integer' is purely stylistic. -- Alien type: unsigned [BITS] Like `signed', but specifies an unsigned integer. -- Alien type: boolean [BITS] Similar to an enumeration type that maps `0' to false and all other values to true. BITS determines the amount of storage allocated to hold the truth value. -- Alien type: single-float A floating-point number in IEEE single format. -- Alien type: double-float A floating-point number in IEEE double format. -- Alien type: function RESULT-TYPE {ARG-TYPE}* A Alien function that takes arguments of the specified ARG-TYPES and returns a result of type RESULT-TYPE. Note that the only context where a `function' type is directly specified is in the argument to `alien-funcall' (see section ?.) In all other contexts, functions are represented by function pointer types: `(* (function ...))'. -- Alien type: system-area-pointer A pointer which is represented in Lisp as a `system-area-pointer' object (*Note System Area Pointers::.) File: cmu-user.info Node: The C-Call Package, Prev: Alien Type Specifiers, Up: Alien Types The C-Call Package ------------------ The `c-call' package exports these type-equivalents to the C type of the same name: `char', `short', `int', `long', `unsigned-char', `unsigned-short', `unsigned-int', `unsigned-long', `float', `double'. `c-call' also exports these types: -- Alien type: void This type is used in function types to declare that no useful value is returned. Evaluation of an `alien-funcall' form will return zero values. -- Alien type: c-string This type is similar to `(* char)', but is interpreted as a null-terminated string, and is automatically converted into a Lisp string when accessed. If the pointer is C `NULL' (or 0), then accessing gives Lisp false. Assigning a Lisp string to a `c-string' structure field or variable stores the contents of the string to the memory already pointed to by that variable. When an Alien of type `(* char)' is assigned to a `c-string', then the `c-string' pointer is assigned to. This allows `c-string' pointers to be initialized. For example: (def-alien-type nil (struct foo (str c-string))) (defun make-foo (str) (let ((my-foo (make-alien (struct foo)))) (setf (slot my-foo 'str) (make-alien char (length str))) (setf (slot my-foo 'str) str) my-foo)) Storing Lisp false writes C `NULL' to the `c-string' pointer. File: cmu-user.info Node: Alien Operations, Prev: Alien Types, Up: Alien Objects, Next: Alien Variables Alien Operations ================ This section describes the basic operations on Alien values. * Menu: * Alien Access Operations:: * Alien Coercion Operations:: * Alien Dynamic Allocation:: File: cmu-user.info Node: Alien Access Operations, Prev: Alien Operations, Up: Alien Operations, Next: Alien Coercion Operations Alien Access Operations ----------------------- -- Function: deref POINTER-OR-ARRAY &restINDICES This function returns the value pointed to by an Alien pointer or the value of an Alien array element. If a pointer, an optional single index can be specified to give the equivalent of C pointer arithmetic; this index is scaled by the size of the type pointed to. If an array, the number of indices must be the same as the number of dimensions in the array type. `deref' can be set with `setf' to assign a new value. -- Function: slot STRUCT-OR-UNION SLOT-NAME This function extracts the value of slot SLOT-NAME from the an Alien `struct' or `union'. If STRUCT-OR-UNION is a pointer to a structure or union, then it is automatically dereferenced. This can be set with `setf' to assign a new value. Note that SLOT-NAME is evaluated, and need not be a compile-time constant (but only constant slot accesses are efficiently compiled.) File: cmu-user.info Node: Alien Coercion Operations, Prev: Alien Access Operations, Up: Alien Operations, Next: Alien Dynamic Allocation Alien Coercion Operations ------------------------- -- Macro: addr ALIEN-EXPR This macro returns a pointer to the location specified by ALIEN-EXPR, which must be either an Alien variable, a use of `deref', a use of `slot', or a use of extern-alien ?. -- Macro: cast ALIEN NEW-TYPE This macro converts ALIEN to a new Alien with the specified NEW-TYPE. Both types must be an Alien pointer, array or function type. Note that the result is not `eq' to the argument, but does refer to the same data bits. -- Macro: sap-alien SAP TYPE -- Function: alien-sap ALIEN-VALUE `sap-alien' converts SAP (a system area pointer *Note System Area Pointers::) to an Alien value with the specified TYPE. TYPE is not evaluated. `alien-sap' returns the SAP which points to ALIEN-VALUE's data. The TYPE to `sap-alien' and the type of the ALIEN-VALUE to `alien-sap' must some Alien pointer, array or record type. File: cmu-user.info Node: Alien Dynamic Allocation, Prev: Alien Coercion Operations, Up: Alien Operations Alien Dynamic Allocation ------------------------ Dynamic Aliens are allocated using the `malloc' library, so foreign code can call `free' on the result of `make-alien', and Lisp code can call `free-alien' on objects allocated by foreign code. -- Macro: make-alien TYPE [SIZE] This macro returns a dynamically allocated Alien of the specified TYPE (which is not evaluated.) The allocated memory is not initialized, and may contain arbitrary junk. If supplied, SIZE is an expression to evaluate to compute the size of the allocated object. There are two major cases: * When TYPE is an array type, an array of that type is allocated and a POINTER to it is returned. Note that you must use `deref' to change the result to an array before you can use `deref' to read or write elements: (defvar *foo* (make-alien (array char 10))) (type-of *foo*) => (alien (* (array (signed 8) 10))) (setf (deref (deref foo) 0) 10) => 10 If supplied, SIZE is used as the first dimension for the array. * When TYPE is any other type, then then an object for that type is allocated, and a POINTER to it is returned. So `(make-alien int)' returns a `(* int)'. If SIZE is specified, then a block of that many objects is allocated, with the result pointing to the first one. -- Function: free-alien ALIEN This function frees the storage for ALIEN (which must have been allocated with `make-alien' or `malloc'.) See also with-alien ?, which stack-allocates Aliens. File: cmu-user.info Node: Alien Variables, Prev: Alien Operations, Up: Alien Objects, Next: Alien Data Structure Example Alien Variables =============== Both local (stack allocated) and external (C global) Alien variables are supported. * Menu: * Local Alien Variables:: * External Alien Variables:: File: cmu-user.info Node: Local Alien Variables, Prev: Alien Variables, Up: Alien Variables, Next: External Alien Variables Local Alien Variables --------------------- -- Macro: with-alien {(NAME TYPE [INITIAL-VALUE])}* {form}* This macro establishes local alien variables with the specified Alien types and names for dynamic extent of the body. The variable NAMES are established as symbol-macros; the bindings have lexical scope, and may be assigned with `setq' or `setf'. This form is analogous to defining a local variable in C: additional storage is allocated, and the initial value is copied. `with-alien' also establishes a new scope for named structures and unions. Any TYPE specified for a variable may contain name structure or union types with the slots specified. Within the lexical scope of the binding specifiers and body, a locally defined structure type FOO can be referenced by its name using: (struct foo) File: cmu-user.info Node: External Alien Variables, Prev: Local Alien Variables, Up: Alien Variables External Alien Variables ------------------------ External Alien names are strings, and Lisp names are symbols. When an external Alien is represented using a Lisp variable, there must be a way to convert from one name syntax into the other. The macros `extern-alien', `def-alien-variable' and def-alien-routine ? use this conversion heuristic: * Alien names are converted to Lisp names by uppercasing and replacing underscores with hyphens. * Conversely, Lisp names are converted to Alien names by lowercasing and replacing hyphens with underscores. * Both the Lisp symbol and Alien string names may be separately specified by using a list of the form: (LISP-SYMBOL ALIEN-STRING) -- Macro: def-alien-variable NAME TYPE This macro defines NAME as an external Alien variable of the specified Alien TYPE. NAME and TYPE are not evaluated. The Lisp name of the variable (see above) becomes a global Alien variable in the Lisp namespace. Global Alien variables are effectively "global symbol macros"; a reference to the variable fetches the contents of the external variable. Similarly, setting the variable stores new contents --- the new contents must be of the declared TYPE. For example, it is often necessary to read the global C variable `errno' to determine why a particular function call failed. It is possible to define errno and make it accessible from Lisp by the following: (def-alien-variable "errno" int) ;; Now it is possible to get the value of the C variable errno simply by ;; referencing that Lisp variable: ;; (print errno) -- Macro: extern-alien NAME TYPE This macro returns an Alien with the specified TYPE which points to an externally defined value. NAME is not evaluated, and may be specified either as a string or a symbol. TYPE is an unevaluated Alien type specifier. File: cmu-user.info Node: Alien Data Structure Example, Prev: Alien Variables, Up: Alien Objects, Next: Loading Unix Object Files Alien Data Structure Example ============================ Now that we have Alien types, operations and variables, we can manipulate foreign data structures. This C declaration can be translated into the following Alien type: struct foo { int a; struct foo *b[100]; }; == (def-alien-type nil (struct foo (a int) (b (array (* (struct foo)) 100)))) With this definition, the following C expression can be translated in this way: struct foo f; f.b[7].a == (with-alien ((f (struct foo))) (slot (deref (slot f 'b) 7) 'a) ;; ;; Do something with f... ) Or consider this example of an external C variable and some accesses: struct c_struct { short x, y; char a, b; int z; c_struct *n; }; extern struct c_struct *my_struct; my_struct->x++; my_struct->a = 5; my_struct = my_struct->n; which can be made be manipulated in Lisp like this: (def-alien-type nil (struct c-struct (x short) (y short) (a char) (b char) (z int) (n (* c-struct)))) (def-alien-variable "my_struct" (* c-struct)) (incf (slot my-struct 'x)) (setf (slot my-struct 'a) 5) (setq my-struct (slot my-struct 'n)) File: cmu-user.info Node: Loading Unix Object Files, Prev: Alien Data Structure Example, Up: Alien Objects, Next: Alien Function Calls Loading Unix Object Files ========================= Foreign object files are loaded into the running Lisp process by `load-foreign'. First, it runs the linker on the files and libraries, creating an absolute Unix object file. This object file is then loaded into into the currently running Lisp. The external symbols defining routines and variables are made available for future external references (e.g. by `extern-alien'.) `load-foreign' must be run before any of the defined symbols are referenced. Note that if a Lisp core image is saved (using save-lisp *Note Saving a Core Image::), all loaded foreign code is lost when the image is restarted. -- Function: load-foreign FILES &key libraries base-file env FILES is a `simple-string' or list of `simple-string's specifying the names of the object files. LIBRARIES is a list of `simple-string's specifying libraries in a format that `ld', the Unix linker, expects. The default value for LIBRARIES is `("-lc")' (i.e., the standard C library). BASE-FILE is the file to use for the initial symbol table information. The default is the Lisp start up code: `path:lisp'. ENV should be a list of simple strings in the format of Unix environment variables (i.e., `A=B', where A is an environment variable and B is its value). The default value for ENV is the environment information available at the time Lisp was invoked. Unless you are certain that you want to change this, you should just use the default. File: cmu-user.info Node: Alien Function Calls, Prev: Loading Unix Object Files, Up: Alien Objects, Next: Step-by-Step Alien Example Alien Function Calls ==================== The foreign function call interface allows a Lisp program to call functions written in other languages. The current implementation of the foreign function call interface assumes a C calling convention and thus routines written in any language that adheres to this convention may be called from Lisp. Lisp sets up various interrupt handling routines and other environment information when it first starts up, and expects these to be in place at all times. The C functions called by Lisp should either not change the environment, especially the interrupt entry points, or should make sure that these entry points are restored when the C function returns to Lisp. If a C function makes changes without restoring things to the way they were when the C function was entered, there is no telling what will happen. * Menu: * alien-funcall:: The alien-funcall Primitive * def-alien-routine:: The def-alien-routine Macro * def-alien-routine Example:: * Calling Lisp from C:: File: cmu-user.info Node: alien-funcall, Prev: Alien Function Calls, Up: Alien Function Calls, Next: def-alien-routine The alien-funcall Primitive --------------------------- -- Function: alien-funcall ALIEN-FUNCTION &restARGUMENTS This function is the foreign function call primitive: ALIEN-FUNCTION is called with the supplied ARGUMENTS and its value is returned. The ALIEN-FUNCTION is an arbitrary run-time expression; to call a constant function, use extern-alien *Note External Alien Variables:: or `def-alien-routine'. The type of ALIEN-FUNCTION must be `(alien (function ...))' or `(alien (* (function ...)))', *Note Alien Type Specifiers::. The function type is used to determine how to call the function (as through it was declared with a prototype.) The type need not be known at compile time, but only known-type calls are efficiently compiled. Limitations: * Structure type return values are not implemented. * Passing of structures by value is not implemented. Here is an example which allocates a `(struct foo)', calls a foreign function to initialize it, then returns a Lisp vector of all the `(* (struct foo))' objects filled in by the foreign call: ;; ;; Allocate a foo on the stack. (with-alien ((f (struct foo))) ;; ;; Call some C function to fill in foo fields. (alien-funcall (extern-alien "mangle_foo" (function void (* foo))) (addr f)) ;; ;; Find how many foos to use by getting the A field. (let* ((num (slot f 'a)) (result (make-array num))) ;; ;; Get a pointer to the array so that we don't have to keep extracting it: (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f 'b)))) ;; ;; Loop over the first N elements and stash them in the result vector. (dotimes (i num) (setf (svref result i) (deref (deref a) i))) result))) File: cmu-user.info Node: def-alien-routine, Prev: alien-funcall, Up: Alien Function Calls, Next: def-alien-routine Example The def-alien-routine Macro --------------------------- -- Macro: def-alien-routine NAME RESULT-TYPE {(ANAME ATYPE [style])}* This macro is a convenience for automatically generating Lisp interfaces to simple foreign functions. The primary feature is the parameter style specification, which translates the C pass-by-reference idiom into additional return values. NAME is usually a string external symbol, but may also be a symbol Lisp name or a list of the Lisp name and the foreign name. If only one name is specified, the other is automatically derived, (*Note External Alien Variables::.) RESULT-TYPE is the Alien type of the return value. Each remaining subform specifies an argument to the foreign function. ANAME is the symbol name of the argument to the constructed function (for documentation) and ATYPE is the Alien type of corresponding foreign argument. The semantics of the actual call are the same as for alien-funcall *Note alien-funcall::. STYLE should be one of the following: :in specifies that the argument is passed by value. This is the default. :in arguments have no corresponding return value from the Lisp function. :out specifies a pass-by-reference output value. The type of the argument must be a pointer to a fixed sized object (such as an integer or pointer). :out and :in-out cannot be used with pointers to arrays, records or functions. An object of the correct size is allocated, and its address is passed to the foreign function. When the function returns, the contents of this location are returned as one of the values of the Lisp function. :copy is similar to :in, but the argument is copied to a pre-allocated object and a pointer to this object is passed to the foreign routine. :in-out is a combination of :copy and :out. The argument is copied to a pre-allocated object and a pointer to this object is passed to the foreign routine. On return, the contents of this location is returned as an additional value. Any efficiency-critical foreign interface function should be inline expanded by preceding `def-alien-routine' with: (declaim (inline LISP-NAME)) In addition to avoiding the Lisp call overhead, this allows pointers, word-integers and floats to be passed using non-descriptor representations, avoiding consing (*Note Non-Descriptor Representations::.) File: cmu-user.info Node: def-alien-routine Example, Prev: def-alien-routine, Up: Alien Function Calls, Next: Calling Lisp from C def-alien-routine Example ------------------------- Consider the C function `cfoo' with the following calling convention: cfoo (a, i) char *str; char *a; /* update */ int *i; /* out */ { /* Body of cfoo. */ } which can be described by the following call to `def-alien-routine': (def-alien-routine "cfoo" void (str c-string) (a char :in-out) (i int :out)) The Lisp function `cfoo' will have two arguments (STR and A) and two return values (A and I). File: cmu-user.info Node: Calling Lisp from C, Prev: def-alien-routine Example, Up: Alien Function Calls Calling Lisp from C ------------------- {There is currently a mechanism for calling Lisp functions from C, but it is rather restricted, and is scheduled for replacement. If you need to call Lisp functions from C, contact us and we will let you know what capabilities are available in the system you have. } File: cmu-user.info Node: Step-by-Step Alien Example, Prev: Alien Function Calls, Up: Alien Objects Step-by-Step Alien Example ========================== This section presents a complete example of an interface to a somewhat complicated C function. This example should give a fairly good idea of how to get the effect you want for almost any kind of C function. Suppose you have the following C function which you want to be able to call from Lisp in the file `test.c': struct c_struct { int x; char *s; }; struct c_struct *c_function (i, s, r, a) int i; char *s; struct c_struct *r; int a[10]; { int j; struct c_struct *r2; printf("i = %d\n", i); printf("s = %s\n", s); printf("r->x = %d\n", r->x); printf("r->s = %s\n", r->s); for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]); r2 = (struct c_struct *) malloc (sizeof(struct c_struct)); r2->x = i + 5; r2->s = "A C string"; return(r2); }; It is possible to call this function from Lisp using the file `test.lisp' whose contents is: ;;; -*- Package: test-c-call -*- (in-package "TEST-C-CALL") (use-package "ALIEN") (use-package "C-CALL") ;;; Define the record c-struct in Lisp. (def-alien-type nil (struct c-struct (x int) (s c-string))) ;;; Define the Lisp function interface to the C routine. It returns a ;;; pointer to a record of type c-struct. It accepts four parameters: ;;; i, an int; s, a pointer to a string; r, a pointer to a c-struct ;;; record; and a, a pointer to the array of 10 ints. ;;; ;;; The INLINE declaration eliminates some efficiency notes about heap ;;; allocation of Alien values. (declaim (inline c-function)) (def-alien-routine c-function (* (struct c-struct)) (i int) (s c-string) (r (* (struct c-struct))) (a (array int 10))) ;;; A function which sets up the parameters to the C function and ;;; actually calls it. (defun call-cfun () (with-alien ((ar (array int 10)) (c-struct (struct c-struct))) (dotimes (i 10) ; Fill array. (setf (deref ar i) i)) (setf (slot c-struct 'x) 20) (setf (slot c-struct 's) "A Lisp String") (with-alien ((res (* (struct c-struct)) (c-function 5 "Another Lisp String" (addr c-struct) ar))) (format t "Returned from C function.~%") (multiple-value-prog1 (values (slot res 'x) (slot res 's)) ;; ;; Deallocate result after we are done using it. (free-alien res))))) To execute the above example, it is necessary to compile the C routine as follows: cc -c test.c In order to enable incremental loading with some linkers, you may need to say: cc -G 0 -c test.c Once the C code has been compiled, you can start up Lisp and load it in: %lisp ;;; Lisp should start up with its normal prompt. ;;; Compile the Lisp file. This step can be done separately. You don't have ;;; to recompile every time. * (compile-file "test.lisp") ;;; Load the foreign object file to define the necessary symbols. This must ;;; be done before loading any code that refers to these symbols. next block ;;; of comments are actually the output of LOAD-FOREIGN. Different linkers ;;; will give different warnings, but some warning about redefining the code ;;; size is typical. * (load-foreign "test.o") ;;; Running library:load-foreign.csh... ;;; Loading object file... ;;; Parsing symbol table... Warning: "_gp" moved from #x00C082C0 to #x00C08460. Warning: "end" moved from #x00C00340 to #x00C004E0. ;;; o.k. now load the compiled Lisp object file. * (load "test") ;;; Now we can call the routine that sets up the parameters and calls the C ;;; function. * (test-c-call::call-cfun) ;;; The C routine prints the following information to standard output. i = 5 s = Another Lisp string r->x = 20 r->s = A Lisp string a[0] = 0. a[1] = 1. a[2] = 2. a[3] = 3. a[4] = 4. a[5] = 5. a[6] = 6. a[7] = 7. a[8] = 8. a[9] = 9. ;;; Lisp prints out the following information. Returned from C function. ;;; Return values from the call to test-c-call::call-cfun. 10 "A C string" * If any of the foreign functions do output, they should not be called from within Hemlock. Depending on the situation, various strange behavior occurs. Under X, the output goes to the window in which Lisp was started; on a terminal, the output will overwrite the Hemlock screen image; in a Hemlock slave, standard output is `/dev/null' by default, so any output is discarded. File: cmu-user.info Node: Interprocess Communication under LISP, Prev: Alien Objects, Up: Top, Next: Debugger Programmer's Interface Interprocess Communication under LISP ************************************* Written by William Lott and Bill Chiles CMU Common Lisp offers a facility for interprocess communication (IPC) on top of using Unix system calls and the complications of that level of IPC. There is a simple remote-procedure-call (RPC) package build on top of TCP/IP sockets. * Menu: * The REMOTE Package:: * The WIRE Package:: * Out-Of-Band Data:: File: cmu-user.info Node: The REMOTE Package, Prev: Interprocess Communication under LISP, Up: Interprocess Communication under LISP, Next: The WIRE Package The REMOTE Package ================== The `remote' package provides simple RPC facility including interfaces for creating servers, connecting to already existing servers, and calling functions in other Lisp processes. The routines for establishing a connection between two processes, `create-request-server' and `connect-to-remote-server', return WIRE structures. A wire maintains the current state of a connection, and all the RPC forms require a wire to indicate where to send requests. * Menu: * Connecting Servers and Clients:: * Remote Evaluations:: * Remote Objects:: * Host Addresses:: 
